Cream of the Crop 1/Cream of the Crop 1.iso/EDITOR/FUGUE_3.ARJ/WF.017

Text File | 1990-11-05 | 18KB | 487 lines

.f3                              - # -              Chapter 17 - Mail Merge
.rm70
.mt5
.mb5
.pl66
.tc
.tc 17. MAIL MERGE ........................................#
CHAPTER 17   MAIL MERGE

Mail Merge, or Merge Printing, is the process of inserting information
into a document while it is being printed. The document is often
printed several times with different information. The most common use
of merge printing is to merge mailing list information into a form
letter or mailing labels. Other applications include invoices,
reports, and any other standard document that requires you to fill in
blanks.

To merge print you need to create the form or template document (also
called the master document). You usually need a data file as well. You
then print the master document using the background print command Ctrl
K P. Word fugue will obey the mail merge dot commands, and insert
information in place of variables in your master document. If you are
using a data file, a copy of the document will be produced for each
set of information in the data file.

A master document contains the text of the document and the
instructions for how the documents are to be produced. These
instructions include variables and special merge print dot commands.
An example would be a form letter and a data file of names and
addresses.

.tc    Variables ..........................................#
Variables

A variable is information that changes from one copy of the document
to another. When you merge print, Word Fugue inserts information for
each variable into each copy. This information can come from a data
file, or you can be prompted for it when you print.

Each variable has a name, and you place the name of the variable into
the master document wherever information is to be inserted. The actual
information inserted in place of the variable is called data.

A variable name can contain up to 20 characters. You can use uppercase
and lowercase letters interchangeably. You can make a name more
readable by using hyphens (-) or underscores (_) to join words in the
variable name.

Where you want to insert variable data, type the variable name between
ampersands (&) in the text of the document:

   &person-name&                         Fred Nurk
   &ADDress_1&                           The street
   &city&, &state& &postcode&            Erehwon, XYZ 9000

If you have never set a value for a variable, it is termed
uninitialised. These variables print their own name, to aid you in
finding them. They usually happen when you misspell their name. word
Fugue cannot match the misspelling, and so prints the name instead.

.tc    Merge Print Dot Commands ...........................#
Merge Print Dot Commands

You type dot commands in the master document to tell Word Fugue the
variable names and where to get the data that goes into them. If you
do not obtain data for a variable name, Word Fugue will print the name
instead. You cannot use a piece of data which is longer than 80
characters. The total amount of data to be merged is limited by the
memory available on your PC.

The following dot commands are available:

                .DF filename delim
                .RV variable list
                .AV prompt,variable
                .SV variable=value
                .MA variable=equation
                .DM message
                .GO go to top of file and start again
                .WS Y or N for Wordstar compatible variable
                    replacement

The .DF command defines the data file containing the variables to be
merged into the text. If you follow the filename by at least one
blank and another character, then that character is used as a
delimiter instead of a comma

        eg .DF names.dat /

means that the file NAMES.DAT contains the variables to be read, and
that the separator between variables is a slash (/). The default is
comma (,).

The .RV command defines the variables to be found on a single line of
the data file. You can have more that one .RV to define different
lines of your master document. If a line of the data file is exhausted
before all the variables are read, the remainder are set to blank.

        eg .RV name,address1,address2

means that each line of the file will look like this:

        Joe Bloggs,17 West street,Newtown DG 9999

If you want to leave a variable blank, then leave it out:

        Joe Bloggs,,Newtown Post Office DG 9999

You can use a different separator, as defined on the .DF line, and put
different variables on different lines:

        .DF names.dat /
        .rv name,address1
        .rv address2

Your file would then look like this:

        Joe Bloggs/17 Westside Ave.,
        Newtown DG 9999

.cp7
The .AV line will prompt you to enter the contents of the variable.
You can include an optional prompt:

        .AV Address1

will display   ADDRESS1?  and open a window for you to enter the
value.

        .AV Enter the address,address1

will display  Enter the address  and open a window for you to enter
the value.

The .SV line sets the variable to the value:

        .SV vara,this is the value for variable A
        .SV addr= This is the address

You can use either comma (,) or equals sign (=). Leading spaces in the
variable are ignored. If you want to include leading spaces, you
should enclose the data within single or double quotes. If you start
with a single quote, you must end with a single quote, and vice
versa:

        .SV company= "   Fugue Software  "

You can set the maximum length of a variable by placing the characters
/L and a length, or /R and a length, or /C and a length, depending on
whether you want your data Left justified or Right justified or
Centred, after the variable name:

        .SV A/L15=Joe Bloggs
        .SV B/R15=Joe Bloggs
        .SV C =Joe Bloggs
        .SV D/C15=Joe Bloggs

        gives
           A = "Joe Bloggs     "
           B = "     Joe Bloggs"
           C = "Joe Bloggs"
           D = "   Joe Bloggs  "

If the line were too long, it would be truncated at the length
specified.

The .MA line allows you to compute values and store them in another
variable:

        .MA VARB=25*10
        .MA varc= &vara&+&varb&
        .MA total_price,&price&*(1-&discount&) * &qty&

The text within the '&' are other variables that will be replaced
before the calculation is done. You can use any functions and
operators that are provided by the pop up calculator, including
booleans, since the same code is used for evaluation.

.cp5
You can also have limited formatting when set in the .MA command.
Follow the variable by $ for dollar format (2 decimal places) and by !
for integer format. The default is as many decimal places as required:

       .MA  a = 1.2345
          &a&           gives 1.2345

       .MA  a$ = 1.2345
          &a&           gives 1.23

       .MA  a! = 1.2345
          &a&           gives 1

The value is actually truncated to the number of places specified when
assigned to the variable

The .DM line will display the following message. You can include
variables which will be substituted before the message is displayed.

        .RV varb
        .DM message is varb = &varb&

will display

       message is varb = the value of variable b

The .GO is used to exit from the current print and go back to the top
of the file (assuming that there are more records to be printed)

.cp8
The .WS is used to determine how variables in the text are replaced.
You can set Y or N. The default is Y. All variables must be embedded
within &s to be recognized and replaced. With the default, this is all
that is needed:

                &address1&
                &address2&

Setting .WS to N will mean that the variables within the text body
must also be embedded inside print control brackets:

                {.&address1&}
                {.&address2&}

.tc    Merge Printing Conditional Commands ................#
Merge Printing Conditional Commands

Additional printing commands for evaluating conditional expressions
and controlling the text that is printed.

                .IF condition           is the IF condition
                .EL                     is the else
                .EI                     ends the IF expression.

You must have an .EI for every .IF, but you do not need to have .EL
(else). The lines following the .IF are evaluated if the .IF were
true, while the lines following the .EL are evaluated if the condition
were false.

.tc      The IF Condition .................................#
The IF Condition

Whether a condition is true is usually determined by comparing one
item with another. If an item can be considered numeric (ie it
consists only of digits), it is converted to a number before the
comparison is done. Otherwise the comparison is done as text. The
following comparisons are available:

        Operator        Meaning

        =               is the same as
        <               is numerically less than or
                        comes alphabetically before
        >               is numerically greater than
                        or comes alphabetically after
        <=              is less than or equal to
        >=              is greater than or equal to
        <>              is not equal or not the same

The most common way to specify a condition to be evaluated is

        .IF item1 operator item2

.cp6
For example, you can compare a merge print variable to a constant (a
word, phrase or number that does not change) or to another merge print
variable:

        .IF &pet& = dog
        .IF &pet& = &pet_2&
        .if &amt& = 12.35

In the first case, the condition is true if the value of the variable
PET is dog. Note that uppercase and lower case are significant. In the
second case, the condition is true if the value of the first variable
is equal to the second variable. In the third case, the condition is
true if the value of the variable is numerically equal to 12.35.

With strings of text, you should enclose them in quotes if leading or
trailing spaces are significant. For 2 text items to be considered the
same (=), they must consist of exactly the same characters.

        .IF "&pet&" = "    dog"
        .if "&pet&" = "    dog's"

mean that the value of the variable PET must have 4 leading spaces.

Words are considered in alphabetic order, so that the following are
true:

        .if cat < catalog
        .IF catalog     >     cat

since cat comes before catalog in the dictionary.

In alphabetic order numbers come before letters. Note that the first
variable determines the type of comparison. Text that cannot be
converted to numbers for a numeric comparison is considered to be
zero:

        .if 2<apple

is FALSE since 2 determines that the comparison will be numeric, and
apple converts to the number 0. Whereas:

        .if apple>2

is TRUE, since apple is alphabetically after 2.

You can also use the .if command with just one variable name, in which
case the condition is true if the variable is not zero or blank.

        .if &pet&

will be true if the variable PET contains a non zero non blank value.

Note 1. that a variable that has never been initialised will return a
        blank in this situation.

     2. If your variable will contain text with spaces, enclose the
        variable in quotes to perform the test:

       .if "&pet&"

.cp6
.tc        Complex Conditions .............................#
Complex Conditions

You can use mathematical equations on either side of the relational
operator, and can join conditions together by using AND and OR. The
following additional operators are available:

        AND             true and true => true
                        anything else => false
        OR              false and false => false
                        anything else   => true

        XOR             true xor false  => true
                        false xor true  => true
                        true xor true   => false
                        false xor false => false

        NOT             not true        => false
                        not false       => true

.cp5
You should use brackets to group parts of the condition for easier
understanding:

    .IF (&PET& = dog) and (&pet2& = cat)
    .IF ((&pet& = dog) or (&pet& = cat)) and (&income& > 25000)

.cp12
.tc      The End If .......................................#
The End If

The .IF dot command is followed by the commands and text to be done if
the condition is true. You must signify to Word Fugue where the text
finishes, so the program knows where to start again if the condition
is false. You indicate this by using the dot command .EI (End If)

Almost anything can come between a .IF and its corresponding .EI. This
can include text or other dot commands:

        .IF (&debt_age& > 30) and (&debt_age& < 60)
        According to our records, you account is overdue. Maybe you
        have overlooked our invoice. Could you please pay $&amt& as
        soon as possible? If you have paid in the last few days,
        please disregard this warning.
        .EI
        .if (&debt_age&>=60)
        .fi nasty.doc
        .ei

In this example, if a debt is between 30 and 60 days old, a warning is
printed. If it is 60 days or more overdue, a stringer message is
printed. If it is under 30 days, no message is printed.

.cp9
.tc      The Else Condition ...............................#
The Else Condition

The else condition says what action to take if the corresponding IF
were false. The phrase ELSE is represented by the dot command .EL.
The previous example could be redone as:

        .if (&debt_age&>=60)
        .fi nasty.doc
        .el
        According to our records, you account is overdue. Maybe you
        have overlooked our invoice. Could you please pay $&amt& as
        soon as possible? If you have paid in the last few days,
        please disregard this warning.
        .EI

You should note a subtle difference here. In the first example, a debt
could be under 30 days, and no message would be printed. In this
example, all debts are assumed to be overdue, so a warning will always
be printed if the debt is under 60 days old.

.tc      Nested Ifs .......................................#
Nested Ifs

You can use conditional print commands and have Word Fugue choose
among three or more alternatives by nesting the commands. For example,
you may want to have different text for debts that are over 90 days,
over 60 days, and over 30 days, as well as not printing a warning if
they are less than 30 days. You could set up individual IFs as in the
first example, and each IF must be phrased in such a way as to exclude
all the other conditions. (This is why we tested > 30 days and < 60
days). Alternatively, you could separate each condition by ELSEs, and
simplify the conditions:

  If the debt is more than 90 days old, insert SOLICITR.DOC, otherwise
  if the debt is more than 60 days old, insert NASTY.DOC, or else if
  the debt is more than 30 days old print a warning, or if the debt is
  less than 2 days old, offer a discount for prompt payment:

.CP16
    ┌───.IF &debt_age& > 90
    │   .fi solicitr.doc
    │   .el
    │┌──.if &debt_age& > 60
    ││  .fi nasty.doc
    ││  .el
    ││┌─.if &debt_age& > 30
    │││ .fi warning.doc
    │││ .el
    │││┌.if &debt_age& < 2
    ││││.fi discount.doc
    │││└.ei
    ││└─.ei
    │└──.ei
    └───.ei

Every .IF must have a corresponding .EI command. There are 4 IFs so
there must be 4 EIs. The lines shown link up the IFs with their
corresponding EIs.

.tc      Command Files ....................................#
Command Files

A command file is a file that contains only (or mainly) dot commands.
Command files can be very useful for controlling merge printing or for
chaining together the chapters of a large document by use of the .FI
file include command:

  Example 1

       ┌─────────────────────────┐
       │.FI letter.txt           │
       │.pa                      │
       │.fi proposal.doc         │
       │.pa                      │
       │.fi specs.doc            │
       └─────────────────────────┘

.cp20
  Example 2

       ┌─────────────────────────────────────────────────────┐
       │.DF names.txt                                        │
       │.RV first_name,last_name                             │
       │.RV address_1                                        │
       │.RV address_2                                        │
       │.RV city,state,postcode                              │
       │.if &postcode&<2000                                  │
       │.fi special.doc                                      │
       │.el                                                  │
       │.if (&postcode&=2620) and (&city& = Queanbeyan)      │
       │.sv state = NSW                                      │
       │.ei                                                  │
       │.fi normal1.doc                                      │
       │.if (&postcode&>=2000) and (&postcode& <=2110)       │
       │.fi offer.doc                                        │
       │.ei                                                  │
       │.ei                                                  │
       └─────────────────────────────────────────────────────┘

.CP5
This document reads a data file called NAMES.TXT, and prints a special
letter if the postcode is less than 2000. Otherwise, it ensures that
all Queanbeyan addresses with postcode 2620 have the state set to NSW
and not ACT. (The postcode 2620 is allocated to parts of ACT and NSW
as well). It then prints a normal letter to these people. If they live
in areas around Sydney (postcode 2000 to 2110), it also prints a
special offer.